Skip to content

docs(adr): record D45 producer seam + ledger hygiene#708

Merged
github-actions[bot] merged 1 commit into
developfrom
docs/adr-d45-ledger
Jul 10, 2026
Merged

docs(adr): record D45 producer seam + ledger hygiene#708
github-actions[bot] merged 1 commit into
developfrom
docs/adr-d45-ledger

Conversation

@frapercan

Copy link
Copy Markdown
Owner

Summary

Docs-only. Writes ADR-D45 with the mechanism traced to code and data on
2026-07-10, and fixes three ledger-hygiene defects.

ADR-D45: the producer seam (rewritten)

D45 already existed (dated 2026-06-22) but framed the seam as a train/serve
value skew. On 2026-07-10 the mechanism was traced and is narrower: a
producer seam, not a value skew and not a storage problem.

  • The fingerprint pins names, not values or producers.
    compute_schema_sha (feature_schema.py:253) and compute_feature_schema_sha
    (feature_schema.py:273) hash sorted column names / family membership through
    short_sha (_hashing.py:29, sha256[:12]). Neither can see a value or
    whether a producer ran.
  • The six LAFA signals are declared in feature_schema.py:
    NUMERIC_FEATURES lines 113, 114, 116, 119, 120, 121; FEATURE_FAMILIES
    classifier (232), self_prior (233), association (234).
  • The export fills all six with a constant 0.0. _lafa_default_fields()
    (protea/core/_leaf_record_builder.py:342) returns them as 0.0; its
    docstring: the classifier_* and association_* columns "stay zero until
    later lafa-integrate slices wire their producers. A well-defined zero, not
    NaN, matching the lineage convention." (The prior note naming
    _reranker_default_fields() was wrong; that method at line 34 fills the KNN
    block, not the six LAFA columns.)
  • Consequence recorded in the sealed run:
    protea-reranker-lab/results/clean_227230/comparison.json has
    feature_exclusions = "association_* and classifier_* (zero-filled in
    export) + ...".
  • The live DB is fine: a 50,000-row sample of go_prediction.features on
    2026-07-10 shows 0.0% zeros for association_total and classifier_score.

Decisions adopted: no silent default (emit NaN or refuse); an export
degeneracy check (a constant declared family fails the job loudly); per-family
provenance (SignalConfig.source of the signal store). Not D45: typing the
six columns is a ~2.5 GB additive storage win (drops the ~75 GB duplicated
features JSONB) that does not close the seam. Honest scope: the
sealed champion (f_micro_w 0.4063, v227 to v230) was trained without the
classifier and association families, so the number is intact; the seam
silently removed three declared families from the model's reach.

Ledger hygiene

  • index.rst intro defect: the strategic range read D1-D31 while the
    series runs to D45 (and the implementation range read 001-008 while
    009 exists). Corrected both, and clarified that D1-D31 came from master
    plan rev 3 while later records were added as the work progressed.
  • Cross-repo D-number collision: PROTEA D39/D40/D41 (destructive-op
    guards, leakage-free temporal eval, lean f32 refpool) collide with
    protea-reranker-lab D39/D40/D41 (FAIR dataset packaging, IA-aligned
    training, universal booster). D34 is intentionally the same decision in
    both. Resolved by a disambiguation note rather than renumbering, because the
    PROTEA numbers (especially D40) are already cited across docs, memory, and
    thesis; qualify the lab records as lab-D39 etc.
  • D38 superseded: its champion designation (prostt5 k=5 binary, Fmax
    0.7291 on v226) is superseded by the sealed board (learned encoder
    d8979601, f_micro_w 0.4063 on the v227 to v230 frame under D40 + D43).
    Marked with the existing :Superseded-by: field convention (as D09 uses) and
    Status Superseded in the index.

Verification

  • check_no_em_dashes.py: OK, 0 violations.
  • check_doc_refs.py: 199 broken refs before and after (all pre-existing
    autodoc :module:/:func:/:class: roles on a clean develop; this PR
    adds none).
  • check_smells.py: OK, no new offenders.

Note on the task premise

The task stated D45 "has never been written down." It existed with a
mis-stated (value-skew) mechanism; this PR corrects it in place rather than
creating a duplicate. Details in the agent report.

Rewrite ADR-D45 to the mechanism traced to code and data on 2026-07-10:
a producer seam, not a value skew and not a storage problem. The six LAFA
signals are declared in protea-contracts feature_schema.py yet
_lafa_default_fields() in _leaf_record_builder.py emits classifier and
association columns as a constant 0.0 because their producers were never
wired into the export. The name-level fingerprint (compute_feature_schema_sha)
matched throughout, so three declared families shipped semantically null with
no check firing. Record the decisions: no silent default (emit NaN or refuse),
an export degeneracy check, and per-family provenance via the signal store.
Note what D45 is NOT: typing the six columns is a separate additive storage
win that does not close the seam. Honest scope: the sealed 0.4063 champion
was trained without those families, so the number is intact.

Ledger hygiene:
- index.rst intro: correct the stale ranges (implementation 001-009,
  strategic D1-D45) and note the D-series is a PROTEA-local ledger.
- Add a cross-repo disambiguation note: PROTEA D39/D40/D41 collide with
  different decisions of the same number in protea-reranker-lab; not
  renumbered because the PROTEA numbers are already cited, so qualify the
  lab records as lab-D39 etc.
- Mark D38 Superseded on its champion designation (learned encoder d8979601
  at f_micro_w 0.4063 on the v227 to v230 frame supersedes the prostt5
  0.7291 designation), using the existing :Superseded-by: field convention.
@github-actions github-actions Bot enabled auto-merge (squash) July 10, 2026 07:33
@github-actions github-actions Bot merged commit 33b3864 into develop Jul 10, 2026
14 checks passed
@codecov

codecov Bot commented Jul 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.85%. Comparing base (b4a9251) to head (d8f1004).
⚠️ Report is 18 commits behind head on develop.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##           develop     #708      +/-   ##
===========================================
- Coverage    88.90%   88.85%   -0.05%     
===========================================
  Files          237      245       +8     
  Lines        17692    18481     +789     
===========================================
+ Hits         15729    16422     +693     
- Misses        1963     2059      +96     
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant